home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1998 July / EnigmA AMIGA RUN 29 (1998)(G.R. Edizioni)(IT)[!][issue 1998-07 & 08].iso / earcd / utils / datatypes / mpegsdt013.lha / mpegsystem.datatype.doc < prev    next >
Text File  |  1998-02-05  |  17KB  |  460 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpegsystem.datatype/--datasheed--
  4. mpegsystem.datatype/--input_format--
  5. mpegsystem.datatype/ADTM_LOADFRAME
  6. mpegsystem.datatype/ADTM_UNLOADFRAME
  7. mpegsystem.datatype/DTM_WRITE
  8. mpegsystem.datatype/MAIN
  9. mpegsystem.datatype/OM_DISPOSE
  10. mpegsystem.datatype/OM_NEW
  11. mpegsystem.datatype/preferences
  12. mpegsystem.datatype/--datasheed--           mpegsystem.datatype/--datasheed--
  13.  
  14.    NAME
  15.        mpegsystem.datatype -- data type for MPEG System streams
  16.  
  17.    SUPERCLASS
  18.        animation.datatype
  19.  
  20.    DESCRIPTION
  21.        The anim datatype, a sub-class of the animation.datatype, is used to
  22.        load and play MPEG System movies.
  23.  
  24.    METHODS
  25.        OM_NEW -- Create a new animation object from a description file. The
  26.            source may only be a file.
  27.  
  28.        OM_DISPOSE -- Dispose instance and contents (embedded objects etc.
  29.            etc.), then pass msg to superclass
  30.  
  31.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  32.            method will be executed like OM_SET downstairs.
  33.  
  34.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  35.            superclass was != 0UL.
  36.  
  37.        DTM_WRITE -- Save object's contents in local (MPEG System) or
  38.            superclass (IFF ILBM) format.
  39.            NOT IMPLEMENTED YET
  40.  
  41.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  42.            from embedded objects like bitmap, colormap and sample.
  43.  
  44.        ADTM_UNLOADFRAME -- Free resources obtained by ADTM_UNLOADFRAME.
  45.            The method is passed to the embedded objects.
  46.  
  47.        All other methods are passed unchanged to superclass.
  48.  
  49.    ATTRIBUTES
  50.        Following attributes are set by the object and are READ-ONLY for
  51.        applications:
  52.  
  53.    BUGS
  54.        - Support for streams with multiple video- and/or audio-streams
  55.          has been removed. The datatype uses currently evertimes
  56.          the first video- and the first audio-stream it finds.
  57.  
  58.        - ADTM_START, ADT_PAUSE, ADTM_STOP and ADTM_LOCATE are not passed
  59.          to the embedded mpevideo.datatype object(s), which may cause
  60.          speed loss if this datatype does speed optimisations based on use
  61.          of those methods.
  62.  
  63.        - The sound may be out-of-sync in the case that a stream
  64.          is very long (more than 60 minutes) due rounding problems.
  65.          (In theory, I did not see the bug...).
  66.  
  67.    TODO
  68.        - Fixing the bugs above.
  69.  
  70.        - Write the "--input_format--"-Autodoc section.
  71.  
  72.        - Leading zeros in the beginning of the file except the "start code"
  73.          begin sequence causes a stream not to be recognized by
  74.          datatypes.library.
  75.          May happen if someone reads raw data from a VideoCD.
  76.  
  77.        - Writing the encoder part, using mpegvideo.datatype V2's encoder
  78.          and mpegaudio.datatype's encoder parts.
  79.  
  80.        - Implementation of ACTION_INFO in the internal filesystem that
  81.          (in theory) optimized reading using async I/O gets correct
  82.          parameters.
  83.  
  84.        - Support for MPEG 2 system streams.
  85.  
  86.        - QUICKSCAN option for optimized and much faster scanning of system
  87.          streams.
  88.  
  89.    HISTORY
  90.        V1.1
  91.          First public release.
  92.  
  93.        V1.2
  94.          - Fixed the descriptor (e.g. the file "MPEG System"). The
  95.            old one contains unneccesary data in the comparisation mask.
  96.            Now the descriptor matches the standard, except that
  97.            leading zero bytes (0x00) causes that the stream won't be
  98.            identified.
  99.            Thanks to Steve Cutting (stevejc@c031aone.net.au) for notifyling
  100.            me the bug.
  101.            Fixed.
  102.  
  103.          - Implemented IGNOREERRORS switch to get Steve Cutting's
  104.            (stevejc@c031aone.net.au) example file
  105.            "http://www.utexas.edustudents/cjso/Chabad/video/chase.mpg"
  106.            working.
  107.  
  108.          - Added missing VERBOSESYNTAX and DEBUG options to find problems
  109.            in the datatype without recompiling the complete source.
  110.  
  111.          - Fixed a bug in the FS:
  112.            The internal filesystem now returns ERROR_SEEK_ERROR of someone
  113.            send an ACTION_SEEK with an unknown position mode
  114.            (e.g. if it is none of OFFSET_(BEGINNING|CURRENT|END).
  115.            Fixed.
  116.  
  117.          - Fixed some problems with the VERBOSE and DEBUG output (missing
  118.            newlines, single lines > 75 chars etc.).
  119.            Fixed.
  120.  
  121.        V1.3
  122.          - Minor code cleanup
  123.  
  124.          - Fixed and updated the autodoc.
  125.  
  126.          - Increased the handlers process priority up to 9
  127.            (normal FFS tasks are running at priority 10) to get more speed
  128.            during scanning.
  129.  
  130.    SEE ALSO
  131.        animation.datatype,
  132.        anim.datatype,
  133.        gifanim.datatype, mpegvideo.datatype,
  134.        picmovie.datatype,
  135.        cdxl.datatype, avi.datatype, quicktime.datatype,
  136.        moviesetter.datatype,
  137.        film.datatype,
  138.        directory.datatype,
  139.        markabletextdtclass
  140.  
  141. mpegsystem.datatype/--input_format--     mpegsystem.datatype/--input_format--
  142.  
  143.     NAME
  144.         MPEG System -- MPEG System stream format
  145.  
  146.     DESCRIPTION
  147.         <Not written yet, sorry>
  148.  
  149.     SEE ALSO
  150.  
  151. mpegsystem.datatype/ADTM_LOADFRAME         mpegsystem.datatype/ADTM_LOADFRAME
  152.  
  153.     NAME
  154.         ADTM_LOADFRAME -- Load frame
  155.  
  156.     FUNCTION
  157.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  158.         data of the animation.
  159.         The method is passed to the embedded mpegvideo.datatype object.
  160.         If successfull, the sample data of struct adtFrame are replaced
  161.         by the corresponsing audio data from the embedded 
  162.         mpegaudio.datatype object.
  163.  
  164.     RESULT
  165.         Returns the result from the embedded mpegvideo.datatype object
  166.         (including Result2).
  167.  
  168. mpegsystem.datatype/ADTM_UNLOADFRAME     mpegsystem.datatype/ADTM_UNLOADFRAME
  169.  
  170.     NAME
  171.         ADTM_UNLOADFRAME -- Unload frame contents
  172.  
  173.     FUNCTION
  174.         The ADTM_UNLOADFRAME method is used to release the contents of a
  175.         animation frame.
  176.  
  177.         This method is passed to the embedded mpegvideo.datatype object.
  178.  
  179.     RESULT
  180.         Returns the result from the embedded mpegvideo.datatype object.
  181.  
  182. mpegsystem.datatype/DTM_WRITE                   mpegsystem.datatype/DTM_WRITE
  183.  
  184.     NAME
  185.         DTM_WRITE -- Save data
  186.  
  187.     FUNCTION
  188.         This method saves the object's contents to disk.
  189.  
  190.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  191.         superclass, animation.datatype, which writes a single IFF ILBM
  192.         picture.
  193.  
  194.         If dtw_mode is DTWM_RAW, the object saved an MPEG System stream to
  195.         the filehandle given, starting with the current frame until
  196.         the end is reached.
  197.         The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames
  198.         and ADTA_FrameIncrement attributes (see TAGS section below).
  199.  
  200.     TAGS
  201.         When writing the local ("raw") format, MPEG System movie, the
  202.         following attributes are recognized:
  203.  
  204.         ADTA_Frame (ULONG) - start frame, saving starts here.
  205.             Defaults to the current frame displayed.
  206.  
  207.         ADTA_Frames (ULONG) - the number of frames to be saved,
  208.             Defaults to (max_num_of_frames - curr_frame).
  209.  
  210.         ADTA_FrameIncrement (ULONG) - frame increment when saving.
  211.             Defaults to 1, which means: "jump to next frame".
  212.  
  213.     NOTE
  214.         This function is not implemented yet. A possible implementation 
  215.         would implement ACTION_WRITE in the virtial implementation and uses
  216.         mpegvideo.datatype and mpegaudio.datatype encoders...
  217.  
  218.     RESULT
  219.         Returns 0 for failure (IoErr() returns result2), non-zero
  220.         for success.
  221.  
  222. mpegsystem.datatype/MAIN                             mpegsystem.datatype/MAIN
  223.  
  224.     INTRODUCTION
  225.         Datatypes class for MPEG 1 System movies.
  226.  
  227.     REQUIREMENTS
  228.         - You need at least Kick/WB 3.0.
  229.  
  230.         - datatypes.library >= V45
  231.  
  232.         - "datatypes/animation.datatype", >= V40.
  233.           "animation.datatype 40.6 (28.09.93)" requires itself some
  234.           libraries/boopsi classes:
  235.         - "realtime.library", >= V39              - for timing
  236.         - "gadgets/tapedeck.gadget" (any version) - for the controls
  237.  
  238.         - mpegvideo.datatype >= V1.6
  239.  
  240.         - mpegaudio.datatype >= V1.1
  241.  
  242.     USAGE
  243.         If the datatypes descriptor file was activated, any attempt to load
  244.         a MPEG System stream using GMultiView, MultiView, AmigaGuide or
  245.         SwitchWindow will load and play the movie.
  246.  
  247.     INSTALLATION
  248.         After unpacking this archive:
  249.         Because this version does not include an Installer script, you have
  250.         to do the installation manually through the shell:
  251.  
  252.           - Unpack this archive and copy the "mpegsystem.datatype" to
  253.             SYS:Classes/DataTypes/:
  254.  
  255.         Copy CLONE FROM "mpegsystem.datatype" TO
  256.          "SYS:Classes/DataTypes/mpegsystem.datatype"
  257.  
  258.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  259.             directory.
  260.             If the descriptor already exists, you should not replace it,
  261.             otherwise you may loose "toolnodes" and other settings stored in
  262.             the existing descriptor.
  263.  
  264.      Copy CLONE FROM "MPEG System(%|.info)" TO DEVS:Datatypes/
  265.  
  266.     SOURCE
  267.         Source is included as an example how to write a datatypes clas
  268.         implements a virtual filesystem and embeds other datatype objects
  269.         for it's work.
  270.  
  271.     MODEL
  272.         This datatype uses a very complex model for decoding MPEG system
  273.         streams. The small drawing below shows the model (OK, the
  274.         drawing is not very good, it's incomplete and so on. If someone
  275.         has the time to draw a better one, send it to me).
  276.  
  277.                            system stream
  278.                                  |
  279.                                  |
  280.                                  Y
  281.              +-------------------------------------------------------------+
  282.              |            mpeg system datatype                             |
  283.              +-----------------------------------------+-------------------+
  284.              |              demultiplexer              | ADTM_LOADFRAME    |
  285.              |  video 0...video n | audio 0... audio n | ADTM_UNLOADFRAME  |
  286.              +-----+-------+------+------+-------+-----+-------------------+
  287.                    |       |             |       |               ^ ^
  288.                    |       |             |       |               | |
  289.                    |       *             |       *               | |
  290.                    |                     |                       | |
  291.                    |                     |                       | |
  292.                    Y                     Y                       | |
  293.       +---------------------+   +---------------------+          | |
  294.       | mpeg video datatype |   | mpeg audio datatype |          | |
  295.       +-----------+---------+   +--------+------------+          | |
  296.                   |                      |                       | |
  297.                   |                      |                       | |
  298.                   |                      +-----------------------+ |
  299.                   +------------------------------------------------+
  300.  
  301.     AUTHOR
  302.         If you want to blame me, report any bugs, or wants a new version
  303.         send your letter to:
  304.                         Roland Mainz
  305.                         Hohenstaufenstraße 8
  306.                         52388 Nörvenich
  307.                         GERMANY
  308.  
  309.         Phone: (+49)(0)2426/901568
  310.         Fax:   (+49)(0)2426/901569
  311.  
  312.         EMAIL is also available (if you want to send me attachments
  313.         larger than 1MB (up to 5MB, more with my permission):
  314.  
  315.         GISBURN@w-specht.rhein-ruhr.de
  316.  
  317.         Up to April 1998 I'm reachable using this email address, too:
  318.         Reinhold.A.Mainz@KBV.DE
  319.  
  320.         | Please put your name and address in your mails !
  321.         | German mailers should add their phone numbers.
  322.         | See BUGS section above when submitting bug reports.
  323.  
  324.         Sorry, but I can only look once a week for mails.
  325.         If you don't hear something from me within three weeks, please
  326.         send your mail again (but watch about new releases) (problems with
  327.         this email port are caused by reconfigurations, hackers, network
  328.         problems etc.).
  329.  
  330.         The  entire  "mpegsystem.datatype"  package  may  be  noncommercially
  331.         redistributed, provided  that  the package  is always  distributed
  332.         in it's complete  form (including it's documentation). A small
  333.         copy fee  for media costs is okay but any kind of commercial
  334.         distribution is strictly forbidden without my permission !
  335.         Comments and suggestions how to improve this program are
  336.         generally appreciated!
  337.  
  338.         Thanks to David Junod, who wrote the animation.datatype and lots of
  339.         the datatypes example code, Matt Dillon for his DICE,
  340.         Olaf 'Olsen' Barthel for his help, ideas and some text clips from 
  341.         his documentations.
  342.  
  343. mpegsystem.datatype/OM_DISPOSE                 mpegsystem.datatype/OM_DISPOSE
  344.  
  345.     NAME
  346.         OM_DISPOSE -- Delete a mpegsystem.datatype object.
  347.  
  348.     FUNCTION
  349.         The OM_DISPOSE method is used to delete an instance of the
  350.         mpegsystem.datatype class. This method is passed to the superclass
  351.         when it has completed.
  352.  
  353.     RESULT
  354.         The object is deleted. 0UL is returned.
  355.  
  356. mpegsystem.datatype/OM_NEW                         mpegsystem.datatype/OM_NEW
  357.  
  358.     NAME
  359.         OM_NEW -- Create a mpegsystem.datatype object.
  360.  
  361.     FUNCTION
  362.         The OM_NEW method is used to create an instance of the
  363.         mpegsystem.datatype class.  This method is passed to the superclass
  364.         first. After this, mpegsystem.datatype parses the prefs file and 
  365.         makes a scan through the system stream to get index information 
  366.         about the single system stream packets.
  367.         After all, the mpegsystem.datatype starts two objects which reads
  368.         the single video and audio streams trougth an internal
  369.         "demultiplexer" (system stream splitter) filesystem.
  370.  
  371.         Subclasses of mpegsystem.datatype are not supported. Any attempt to
  372.         create a subclass object of mpegsystem.datatype will be rejected by
  373.         this method.
  374.  
  375.     ATTRIBUTES
  376.         The following attributes can be specified at creation time.
  377.  
  378.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  379.             attribute. Only DTST_FILE is supported.
  380.             If any other type was set in a given DTA_SourceType,
  381.             OM_NEW will be rejected.
  382.             Defaults to DTST_FILE.
  383.  
  384.         DTA_Handle -- For DTST_FILE, a BPTR filehandle is expected. This
  385.             handle will be created by datatypesclass depeding on the DTF_#?
  386.             flag, which is DTF_BINARY here.  DTST_FILE, datatypesclass
  387.             creates a file handle from the given DTA_Name and DTA_Handle
  388.             (a BPTR returned by Lock).
  389.             A DTST_RAM (create empty object) source type requires a NULL
  390.             handle.
  391.  
  392.     RESULT
  393.         If the object was created a pointer to the object is returned,
  394.         otherwise NULL is returned.
  395.  
  396. mpegsystem.datatype/preferences               mpegsystem.datatype/preferences
  397.  
  398.    NAME
  399.        preferences
  400.  
  401.    DESCRIPTION
  402.        The "ENV:Classes/DataTypes/mpegsystem.prefs" file contains global
  403.        settings for the datatype.
  404.        The preferences file is an ASCII file containing one line where the
  405.        preferences can be set.
  406.        It can be superset by a local variable with the same name.
  407.  
  408.        Each line can contain settings, special settings for some projects
  409.        can be set using the MATCHPROJECT option.
  410.        Lines beginning with a '#' or ';' chars are treated as comments.
  411.        Lines are limitted to 256 chars.
  412.  
  413.    TEMPLATE
  414.        MATCHPROJECT/K,VERBOSE/S,VERBOSESYNTAX/S,NOVERBOSESYNTAX/S,
  415.        VERBOSEDEBUG=DEBUG/S,NOVERBOSEDEBUG=NODEBUG/S,IGNOREERRORS/S,
  416.        NOIGNOREERRORS/S
  417.  
  418.        MATCHPROJECT -- The settings in this line belongs only to this
  419.            project(s), e.g. if the case-insensitive pattern does not match,
  420.            this line is ignored.
  421.            The maximum length of the pattern is 128 chars.
  422.            Defaults to #?, which matches any project.
  423.  
  424.        VERBOSE -- Print information about the animation. Currently
  425.           the frame numbers and the used compression are printed, after all
  426.           number of scanned/loaded frames, set FPS rate, dimensions (width/
  427.           height/depth), sample information etc.
  428.  
  429.        VERBOSESYNTAX -- Print information about syntax errors
  430.  
  431.        NOVERBOSESYNTAX -- Turns the VERBOSESYNTAX option off.
  432.  
  433.        DEBUG
  434.        VERBOSEDEBUG -- Turns debugging mode on to get internal debugging
  435.            info without recompiling the whole source.
  436.  
  437.        NODEBUG
  438.        NOVERBOSEDEBUG -- Turns the DEBUG option off.
  439.  
  440.        IGNOREERRORS -- Ignores errors if system stream parsing fails;
  441.            the video+audio parts attempts to load the data until the
  442.            last scanned packet occurs.
  443.  
  444.        NOIGNOREERRORS -- Turns the IGNOREERRORS option off.
  445.  
  446.    NOTE
  447.        - An invalid prefs file line will be ignored and forces the VERBOSE
  448.          output.
  449.  
  450.    BUGS
  451.        - Low memory may cause that the prefs file won't be parsed.
  452.  
  453.        - Lines are limitted to 256 chars
  454.  
  455.        - An invalid prefs file line will be ignored.
  456.  
  457.        - The sample path length is limitted to 200 chars. A larger
  458.          value may crash the machine if an error occurs.
  459.  
  460.